﻿<!DOCTYPE HTML>
<html lang="zh">
<head>
<title>SoundSet - 语法 &amp; 使用 | AutoHotkey v2</title>
<meta name="description" content="The SoundSet function changes various settings of a sound device (master mute, master volume, etc.)" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
<script type="text/javascript">$(function(){0<=window.navigator.userAgent.toLowerCase().indexOf("ucbrowser")&&CaoNiMaDeUc()})</script>
</head>
<body>

<h1>SoundSet</h1>

<p>Changes various settings of a sound device (master mute, master volume, etc.)</p>

<pre class="Syntax"><span class="func">SoundSet</span> NewSetting <span class="optional">, ComponentType, ControlType, DeviceNumber</span></pre>
<h2 id="Parameters">参数</h2>
<dl>

  <dt>NewSetting</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#numbers">整数</a>或<a href="../Concepts.htm#numbers">浮点数</a></p>
    <p>Percentage number between -100 and 100 inclusive (it can be a floating point number). If the number begins with a plus or minus sign, the <strong>current setting</strong> will be adjusted up or down by the indicated amount. Otherwise, the setting will be set explicitly to the level indicated by <em>NewSetting</em>.</p>
    <p>For <em>ControlTypes</em> with only two possible settings -- namely ONOFF, MUTE, MONO, LOUDNESS, STEREOENH, and BASSBOOST -- any positive number will turn on the setting and a zero will turn it off. However, if the number begins with a plus or minus sign, the setting will be toggled (set to the opposite of its current state).</p>
  </dd>

  <dt>ComponentType</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#strings">字符串</a></p>
    <p>If omitted or blank, it defaults to the word MASTER. Otherwise, it can be one of the following words: MASTER (synonymous with SPEAKERS), DIGITAL, LINE, MICROPHONE, SYNTH, CD, TELEPHONE, PCSPEAKER, WAVE, AUX, ANALOG, HEADPHONES, or N/A. If the sound device lacks the specified <em>ComponentType</em>, ErrorLevel will indicate the problem.</p>
    <p>The component labeled Auxiliary in some mixers might be accessible as ANALOG rather than AUX.</p>
    <p>If a device has more than one instance of <em>ComponentType</em> (two of type LINE, for example), usually the first contains the playback settings and the second contains the recording settings. To access an instance other than the first, append a colon and a number to this parameter. 例如: <code>Analog:2</code> is the second instance of the analog component.</p>
  </dd>

  <dt>ControlType</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#strings">字符串</a></p>
    <p>If omitted or blank, it defaults to VOLUME. Otherwise, it can be one of the following words: VOLUME (or VOL), ONOFF, MUTE, MONO, LOUDNESS, STEREOENH, BASSBOOST, PAN, QSOUNDPAN, BASS, TREBLE, EQUALIZER, or the number of a valid control type (see <a href="#ExSoundcard">soundcard analysis script</a>). If the specified <em>ComponentType</em> lacks the specified <em>ControlType</em>, ErrorLevel will indicate the problem.</p>
    <p class="note"><strong>Note:</strong> Sound devices usually support only VOLUME (or VOL) and MUTE, although others may be available depending on Windows and the sound device.</p>
  </dd>

  <dt>DeviceNumber</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#numbers">整数</a></p>
    <p>A number between 1 and the total number of supported devices. If this parameter is omitted, it defaults to the system's default device for playback. The <a href="#ExSoundcard">soundcard analysis script</a> may help determine which number to use.</p>
  </dd>

</dl>
<h2 id="Error_Handling">错误处理</h2>
<p>如果函数成功, <a href="../misc/ErrorLevel.htm">ErrorLevel</a> 设置为 0. 否则, 它被设置为以下短语之一:</p>
<ul>
    <li>Invalid Control Type or Component Type</li>
    <li>Can't Open Specified Mixer</li>
    <li>Mixer Doesn't Support This Component Type</li>
    <li>Mixer Doesn't Have That Many of That Component Type</li>
    <li>Component Doesn't Support This Control Type</li>
    <li>Can't Get Current Setting</li>
    <li>Can't Change Setting</li>
</ul>
<h2 id="Remarks">备注</h2>
<p>For more functionality and finer grained control over audio, consider using the <a href="https://www.autohotkey.com/board/topic/21984-vista-audio-control-functions/">VA library</a>.</p>
<p>An alternative way to adjust the volume is to have the script send volume-control keystrokes to change the master volume for the entire system, such as in the example below:</p>
<pre>Send "{Volume_Up}"  <em>; Raise the master volume by 1 interval (typically 5%).</em>
Send "{Volume_Down 3}"  <em>; Lower the master volume by 3 intervals.</em>
Send "{Volume_Mute}"  <em>; Mute/unmute the master volume.</em></pre>
<p>To discover the capabilities of the sound devices (mixers) installed on the system -- such as the available component types and control types -- run the <a href="#ExSoundcard">soundcard analysis script</a>.</p>
<p>SoundSet attempts to preserve the existing balance when changing the volume level.</p>
<p>Use <a href="SoundGet.htm">SoundGet</a> to retrieve the current value of a setting.</p>
<h2 id="Related">相关</h2>
<p><a href="SoundGet.htm">SoundGet</a>, <a href="SoundPlay.htm">SoundPlay</a></p>
<h2 id="Examples">示例</h2>
<div class="ex" id="ExBasic">
<p><a href="#ExBasic">#1</a>: Basic examples</p>
<pre>SoundSet 50  <em>; Set the master volume to 50%</em>
SoundSet "+10"  <em>; Increase master volume by 10%</em>
SoundSet -10  <em>; Decrease master volume by 10%</em>
SoundSet 1, "Microphone", "Mute"  <em>; mute the microphone</em>
SoundSet "+1", , "Mute"  <em>; Toggle the master mute (set it to the opposite state)</em>
SoundSet "+20", "Master", "Bass"  <em>; Increase bass level by 20%.</em>
if ErrorLevel
    MsgBox "The BASS setting is not supported for MASTER."</pre>
</div>

<div class="ex" id="ExSoundcard">
<p><a href="#ExSoundcard">#2</a>: Soundcard Analysis. Use the following script to discover your soundcard's capabilities (component types and control types). It displays the results in a simple ListView. Alternatively, a script for AutoHotkey v1.1 which provides more detail (such as display names of devices) can be downloaded from the following forum topic: <a href="https://www.autohotkey.com/board/topic/90877-/">https://www.autohotkey.com/board/topic/90877-/</a></p>
<pre>
<em>; Most of the pure numbers below probably don't exist in any mixer, but they're queried for completeness.
; The numbers correspond to the following items (in order): CUSTOM, BOOLEANMETER, SIGNEDMETER, PEAKMETER,
; UNSIGNEDMETER, BOOLEAN, BUTTON, DECIBELS, SIGNED, UNSIGNED, PERCENT, SLIDER, FADER, SINGLESELECT, MUX,
; MULTIPLESELECT, MIXER, MICROTIME, MILLITIME</em>
ControlTypes := "VOLUME,ONOFF,MUTE,MONO,LOUDNESS,STEREOENH,BASSBOOST,PAN,QSOUNDPAN,BASS,TREBLE,EQUALIZER,0x00000000,0x10010000,0x10020000,0x10020001,0x10030000,0x20010000,0x21010000,0x30040000,0x30020000,0x30030000,0x30050000,0x40020000,0x50030000,0x70010000,0x70010001,0x71010000,0x71010001,0x60030000,0x61030000"

ComponentTypes := "MASTER,HEADPHONES,DIGITAL,LINE,MICROPHONE,SYNTH,CD,TELEPHONE,PCSPEAKER,WAVE,AUX,ANALOG,N/A"

<em>; Create a ListView and prepare for the main loop:</em>
Gui := GuiCreate()
InfoText := Gui.Add("Text", "w400 h400", "Gathering Soundcard Info...")
LV := Gui.Add("ListView", "wp hp xp yp", "Component Type|Control Type|Setting|Mixer")
LV.Visible := false
LV.ModifyCol(4, "Integer")
Gui.Show

Loop  <em>; For each mixer number that exists in the system, query its capabilities.</em>
{
    CurrMixer := A_Index
    Setting := SoundGet(,, CurrMixer)
    if ErrorLevel = "Can't Open Specified Mixer"  <em>; Any error other than this indicates that the mixer exists.</em>
        break
    <em>; For each component type that exists in this mixer, query its instances and control types:</em>
    For i, CurrComponent in StrSplit(ComponentTypes, ",")
    {
        <em>; First check if this component type even exists in the mixer:</em>
        Setting := SoundGet(CurrComponent,, CurrMixer)
        if ErrorLevel = "Mixer Doesn't Support This Component Type"
            continue  <em>; Start a new iteration to move on to the next component type.</em>
        Loop  <em>; For each instance of this component type, query its control types.</em>
        {
            CurrInstance := A_Index
            <em>; First check if this instance of this instance even exists in the mixer:</em>
            Setting := SoundGet(CurrComponent ":" CurrInstance,, CurrMixer)
            <em>; Checking for both of the following errors allows this script to run on older versions:</em>
            if ErrorLevel = "Mixer Doesn't Have That Many of That Component Type"
            || ErrorLevel = "Invalid Control Type or Component Type"
                break  <em>; No more instances of this component type.</em>
            <em>; Get the current setting of each control type that exists in this instance of this component:</em>
            For i, CurrControl in StrSplit(ControlTypes, ",")
            {
                Setting := SoundGet(CurrComponent ":" CurrInstance, CurrControl, CurrMixer)
                <em>; Checking for both of the following errors allows this script to run on older versions:</em>
                if ErrorLevel = "Component Doesn't Support This Control Type"
                || ErrorLevel = "Invalid Control Type or Component Type"
                    continue
                if ErrorLevel  <em>; Some other error, which is unexpected so show it in the results.</em>
                    Setting := ErrorLevel
                ComponentString := CurrComponent
                if CurrInstance &gt; 1
                    ComponentString .= ":" CurrInstance
                if Setting is "float"
                    Setting := Format("{:0.2f}", Setting)  <em>; Limit number of decimal places in percentages to two.</em>
                LV.Add(, ComponentString, CurrControl, Setting, CurrMixer)
            }  <em>; For each control type.</em>
        }  <em>; For each component instance.</em>
    }  <em>; For each component type.</em>
}  <em>; For each mixer.</em>

Loop LV.GetCount("Col")  <em>; Auto-size each column to fit its contents.</em>
    LV.ModifyCol(A_Index, "AutoHdr")

InfoText.Visible := false
LV.Visible := true
return</pre>
</div>

</body>
</html>